<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr" lang="en"><head>


  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>uidldocumentation [UIDL]</title>
  

  <meta name="generator" content="DokuWiki Release 2007-06-26b">
<meta name="robots" content="noindex,nofollow">
<meta name="date" content="2008-01-12T14:37:36+0200">
<meta name="keywords" content="uidldocumentation">
<link rel="search" type="application/opensearchdescription+xml" href="http://www.uidl.net/dokuwiki/lib/exe/opensearch.php" title="UIDL">
<link rel="start" href="http://www.uidl.net/dokuwiki/">
<link rel="contents" href="http://www.uidl.net/dokuwiki/doku.php?id=uidldocumentation&amp;do=index" title="Index">
<link rel="alternate" type="application/rss+xml" title="Recent Changes" href="http://www.uidl.net/dokuwiki/feed.php">
<link rel="alternate" type="application/rss+xml" title="Current Namespace" href="http://www.uidl.net/dokuwiki/feed.php?mode=list&amp;ns=">
<link rel="alternate" type="text/html" title="Plain HTML" href="http://www.uidl.net/dokuwiki/doku.php?do=export_xhtml&amp;id=uidldocumentation">
<link rel="alternate" type="text/plain" title="Wiki Markup" href="http://www.uidl.net/dokuwiki/doku.php?do=export_raw&amp;id=uidldocumentation">
<link rel="stylesheet" media="all" type="text/css" href="index_files/css.css">
<link rel="stylesheet" media="screen" type="text/css" href="index_files/css_002.css">
<link rel="stylesheet" media="print" type="text/css" href="index_files/css_003.css">
<script type="text/javascript" charset="utf-8" src="index_files/js.php"></script>

  <link rel="shortcut icon" href="http://www.uidl.net/dokuwiki/lib/tpl/default/images/favicon.ico"></head><body>
<div class="dokuwiki">
  
  <div class="stylehead">

    <div class="header">
      <div class="pagename">
        [[<a href="http://www.uidl.net/dokuwiki/doku.php?id=uidldocumentation&amp;do=backlink">uidldocumentation</a>]]
      </div>
      <div class="logo">
        <a href="http://www.uidl.net/dokuwiki/doku.php?id=" name="dokuwiki__top" id="dokuwiki__top" accesskey="h" title="[ALT+H]">UIDL</a>      </div>

      <div class="clearer"></div>
    </div>

    
    <div class="bar" id="bar__top">
      <div class="bar-left" id="bar__topleft">
        <form class="button" method="post" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="edit" type="hidden"><input name="rev" value="" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Edit this page" class="button" accesskey="e" title="Edit this page [ALT+E]" type="submit"></div></form>        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="revisions" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Old revisions" class="button" accesskey="o" title="Old revisions [ALT+O]" type="submit"></div></form>      </div>

      <div class="bar-right" id="bar__topright">
        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="recent" type="hidden"><input name="id" value="" type="hidden"><input value="Recent changes" class="button" accesskey="r" title="Recent changes [ALT+R]" type="submit"></div></form>        <form action="/dokuwiki/doku.php?id=" accept-charset="utf-8" class="search" id="dw__search"><div class="no"><input name="do" value="search" type="hidden"><input id="qsearch__in" accesskey="f" name="id" class="edit" title="[ALT+F]" type="text"><input value="Search" class="button" title="Search" type="submit"><div style="display: none;" id="qsearch__out" class="ajax_qsearch JSpopup"></div></div></form>&nbsp;
      </div>

      <div class="clearer"></div>
    </div>

        <div class="breadcrumbs">
      Trace: <span class="bcsep">»</span> <a href="http://www.uidl.net/dokuwiki/doku.php?id=wiki:syntax" class="breadcrumbs" title="wiki:syntax">syntax</a> <span class="bcsep">»</span> <a href="http://www.uidl.net/dokuwiki/doku.php?id=start" class="breadcrumbs" title="start">start</a> <span class="bcsep">»</span> <span class="curid"><a href="http://www.uidl.net/dokuwiki/doku.php?id=uidldocumentation" class="breadcrumbs" title="uidldocumentation">uidldocumentation</a></span>          </div>
    
    
  </div>
  
  
  <div class="page">
    <!-- wikipage start -->
    


<h3><a name="uidluser_interface_description_language_-_reference_documentation" id="uidluser_interface_description_language_-_reference_documentation">UIDL: User Interface Description Language - Reference Documentation</a></h3>
<div class="level3">

</div>

<h4><a name="authors" id="authors">Authors</a></h4>
<div class="level4">

<p>
 <a href="mailto:mailto:dominic.cioccarelli@uidl.net" class="mail JSnocheck" title="mailto:dominic.cioccarelli@uidl.net">Dominic Cioccarelli</a>
</p>

</div>

<h4><a name="index" id="index">Index</a></h4>
<div class="level4">
<ul>
<li class="level1"><div class="li"> <a href="#introduction" title="uidldocumentation ↵" class="wikilink1">Introduction</a></div>
</li>
<li class="level1"><div class="li"> <a href="#downloading_installing_building_uidl" title="uidldocumentation ↵" class="wikilink1">Downloading, Installing &amp; Building UIDL</a></div>
<ul>
<li class="level2"><div class="li"> <a href="#downloading" title="uidldocumentation ↵" class="wikilink1">Downloading</a></div>
</li>
<li class="level2"><div class="li"> <a href="#installation" title="uidldocumentation ↵" class="wikilink1">Installation</a></div>
</li>
<li class="level2"><div class="li"> <a href="#running_the_example_applications" title="uidldocumentation ↵" class="wikilink1">Running the Example Applications</a></div>
</li>
<li class="level2"><div class="li"> <a href="#building_uidl" title="uidldocumentation ↵" class="wikilink1">Building</a></div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <a href="#uidl_the_browser" title="uidldocumentation ↵" class="wikilink1">UIDL: The Browser</a></div>
<ul>
<li class="level2"><div class="li"> <a href="#uidl_browser_deployment" title="uidldocumentation ↵" class="wikilink1">UIDL Browser Deployment</a></div>
</li>
<li class="level2"><div class="li"> <a href="#the_uidl_browser" title="uidldocumentation ↵" class="wikilink1">The UIDL Browser</a></div>
</li>
<li class="level2"><div class="li"> <a href="#running_a_uidl_application_with_java_web_start" title="uidldocumentation ↵" class="wikilink1">Running a UIDL application with Java Web Start</a></div>
</li>
<li class="level2"><div class="li"> <a href="#embedding_the_uidl_browser_in_an_applet" title="uidldocumentation ↵" class="wikilink1">Embedding the UIDL Browser in an Applet</a></div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <a href="#writing_uidl_applications" title="uidldocumentation ↵" class="wikilink1">Writing UIDL Applications</a></div>
<ul>
<li class="level2"><div class="li"> <a href="#the_javascript_interpreter" title="uidldocumentation ↵" class="wikilink1">The JavaScript Interpreter</a></div>
</li>
<li class="level2"><div class="li"> <a href="#core_uidl_browser_objects" title="uidldocumentation ↵" class="wikilink1">Core UIDL browser objects</a></div>
</li>
<li class="level2"><div class="li"> <a href="#importing_java_packages" title="uidldocumentation ↵" class="wikilink1">Importing Java Packages</a></div>
</li>
<li class="level2"><div class="li"> <a href="#organizing_code" title="uidldocumentation ↵" class="wikilink1">Organizing Code</a></div>
</li>
<li class="level2"><div class="li"> <a href="#creating_a_simple_application" title="uidldocumentation ↵" class="wikilink1">Creating a Simple Application</a></div>
</li>
<li class="level2"><div class="li"> <a href="#creating_a_more_complex_application" title="uidldocumentation ↵" class="wikilink1">Creating a more complex Application</a></div>
</li>
<li class="level2"><div class="li"> <a href="#debugging_uidl_applications" title="uidldocumentation ↵" class="wikilink1">Debugging UIDL applications</a></div>
</li>
<li class="level2"><div class="li"> <a href="#other_scripting_resources" title="uidldocumentation ↵" class="wikilink1">Other Scripting Resources</a></div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <a href="#uidl_remoting" title="uidldocumentation ↵" class="wikilink1">UIDL Remoting</a></div>
<ul>
<li class="level2"><div class="li"> <a href="#json-rpc" title="uidldocumentation ↵" class="wikilink1">JSON-RPC</a></div>
</li>
<li class="level2"><div class="li"> <a href="#spring_remoting" title="uidldocumentation ↵" class="wikilink1">Spring Remoting</a></div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <a href="#the_carsales_sample_application" title="uidldocumentation ↵" class="wikilink1">The "CarSales" Sample Application</a></div>
</li>
<li class="level1"><div class="li"> <a href="#uidl_security" title="uidldocumentation ↵" class="wikilink1">UIDL Security</a></div>
</li>
</ul>

</div>

<h4><a name="introduction" id="introduction">Introduction</a></h4>
<div class="level4">

<p> Traditionally, enterprise applications were built using a
client-server approach. As web browsers became more widespread, many
application developers preferred to provide a “web interface” as it
allowed for transparent deployment of new functionality. This lead to
the growth of web applications as we know them today.
</p>

<p>The unfortunate side effect of web applications is that web browsers
were only ever designed to display static content. This has meant that
designing an application to run within a web browser has been a non
trivial task and has often lead to applications which are not as
responsive or interactive as would have been the case with a rich
client version. Thus, whilst web applications provide ease of
deployment, they often decrease developer productivity and the overall
ease of use of the UI is compromised.
</p>

<p>Recognizing the constraints of web browsers, there has been a recent
trend towards Rich Internet Applications (RIAs) which aim to harness
the ease of deployment of web applications and the rich user experience
provided by traditional rich client applications. RIA technology is
multi faceted and extends from <acronym title="Asynchronous JavaScript and XML">AJAX</acronym>
applications which “extend” the usefulness of traditional browsers by
allowing asynchronous communications (and hence reducing whole page
refreshes) to more complex solutions such as Flex / Laszlo which use
the Macromedia Flash environment included with most browsers to render
the UI.
</p>

<p>The UIDL approach is somewhat different in that it uses a Java
applet or Java webstart application to act as a pseudo browser
environment. This “new” browser is capable of interpreting both <acronym title="HyperText Markup Language">HTML</acronym>
and UIDL code, which is basically JavaScript with extensions to allow
access to the native windowing system and remote communications.
</p>

<p>
UIDL hopes to provide the following benefits: 
</p>
<ul>
<li class="level1"><div class="li"> A “universal” client which can run
anywhere (in a browser, on the desktop) and can be used to render
applications written in UIDL. This means that there is no need to worry
about deployment or software upgrades.</div>
</li>
<li class="level1"><div class="li"> Mechanisms for providing easy
access to server based resources. Ideally, applications can be modified
to run with a UIDL interface without extensive additions and without
modifying the underlying code. In many cases an application <acronym title="Application Programming Interface">API</acronym> can be exposed to transparently allow “remoting”.</div>
</li>
<li class="level1"><div class="li"> An environment which provides high
developer productivity. As UIDL is based on JavaScript (an interpreted
language) UIDL scripts can be written and tested quickly. The use of a
scripted language for the UI encourages the separation of concerns and
allows less skilled developers to build the UI whilst the more senior
developers concentrate on the more complex code running on the server.</div>
</li>
</ul>

</div>

<h4><a name="downloading_installing_building_uidl" id="downloading_installing_building_uidl">Downloading, Installing &amp; Building UIDL</a></h4>
<div class="level4">

</div>

<h5><a name="downloading" id="downloading">Downloading</a></h5>
<div class="level5">

<p>
 The main distribution site for UIDL releases is Google code, at <a href="http://code.google.com/p/uidl/downloads/list" class="urlextern" title="http://code.google.com/p/uidl/downloads/list" rel="nofollow">http://code.google.com/p/uidl/downloads/list</a>. The SVN repository for the UIDL source code is hosted by Google code at <a href="http://code.google.com/p/uidl/source" class="urlextern" title="http://code.google.com/p/uidl/source" rel="nofollow">http://code.google.com/p/uidl/source</a>.
</p>

</div>

<h5><a name="installation" id="installation">Installation</a></h5>
<div class="level5">

<p> The UIDL distribution comes with pre-built UIDL JARs and all
supporting JARs. Most of the files in the distribution are not for the
UIDL browser itself but rather for the supporting examples (which
require things like Spring and Hibernate).
</p>

<p>
You should unzip the distribution into a local directory. From here you will find the directory structure to be as follows:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2FdirStructure.GIF" class="media" title="http://java.uidl.net/doc/images/dirStructure.GIF"><img src="index_files/fetch.gif" class="media" alt=""></a>
</p>

<p>
The source files for the UIDL browser are located in the <code>/src</code> directory whilst the source files for the example scenarios are are located in the <code>/examples</code> directory. Ant build scripts are provided for both the browser and the examples and are located in the /build directory. The <code>/lib</code>
directory contains all the Java libraries required to build either the
browser or the example applications. Run time JARs to support the
example applications are located in <code>/webapp/WEB-INF/lib</code>.
</p>

<p>
The <code>/webapp</code> directory contains all the server side
code required for the example applications and is also used to server
the initial files for the UIDL browser and the subsequent UIDL pages.
</p>

</div>

<h4><a name="running_the_example_applications" id="running_the_example_applications">Running the Example Applications</a></h4>
<div class="level4">

</div>

<h5><a name="statically_hosted_files" id="statically_hosted_files">Statically Hosted Files</a></h5>
<div class="level5">

<p>
 To illustrate how simple it is to run a very simple (static) UIDL application, you can simply copy the contents of the <code>/webapp</code> directory to a normal web server. From there you can navigate to the index page (<code>index.html</code>)
and run either the Java WebStart or Applet version of the UIDL browser.
Once running the browser, you can run any of the static UIDL examples
(i.e. those which don't use remoting). These include ”<code>simple.uidl</code>” and ”<code>converter.uidl</code>”.
</p>

</div>

<h5><a name="using_a_web_application_server" id="using_a_web_application_server">Using a Web Application Server</a></h5>
<div class="level5">

<p> Obviously, more complex applications will require some interaction
with business logic running on the server. As a result, we need to run
the server side code for the example applications within a web
application container. This can be done in one of three ways: </p>
<ul>
<li class="level1"><div class="li"> You can simply run ”<code>webserver.bat</code>” or ”<code>webserver.sh</code>”
from the root directory. This will used an embedded version of the
Jetty web application server to publish the contents of the “webapp”
sub-directory.</div>
</li>
<li class="level1"><div class="li"> The <code>/webapp</code>
subdirectory is already in the correct format (exploded WAR) for most
web application servers (e.g. Tomcat). You can configure your
application server to point directly to the /webapp directory which was
part of the UIDL distribution that you unzipped previously. In Tomcat,
this would be done using a context descriptor (e.g. uidl.xml) similar
to the following:</div>
</li>
</ul>
<pre class="code xml">      <span class="sc3"><span class="re1">&lt;Context</span> <span class="re0">docBase</span>=<span class="st0">"C:/cep/uidl/webapp"</span> <span class="re0">debug</span>=<span class="st0">"0"</span> <span class="re0">privileged</span>=<span class="st0">"false"</span> <span class="re0">reloadable</span>=<span class="st0">"true"</span><span class="re2">&gt;</span></span>
      <span class="sc3"><span class="re1">&lt;/Context<span class="re2">&gt;</span></span></span></pre><ul>
<li class="level1"><div class="li"> You can simply build the UIDL WAR
file and deploy it to your web server as you would any other WAR file.
Building the WAR file is described in the next section.</div>
</li>
</ul>

</div>

<h5><a name="configuring_the_carsales_data_source" id="configuring_the_carsales_data_source">Configuring the "CarSales" Data Source</a></h5>
<div class="level5">

<p>
 Irrespective of how you run the UIDL web application, you should look at the ”<code>applicationContext.xml</code>” file (in the <code>/WEB-INF directory</code>) to see how the CarSales Derby database is configured. The location of the database is defined by the JDBC <acronym title="Uniform Resource Identifier">URI</acronym>, which is located in the Spring ”<code>applicationContext.xml</code>”, i.e.:
</p>
<pre class="code xml"><span class="sc3"><span class="coMULTI">&lt;!-- Configuration for an application managed JDBC datasource --&gt;</span></span>
<span class="sc3"><span class="re1">&lt;bean</span> <span class="re0">id</span>=<span class="st0">"carsalesDataSource"</span> <span class="re0">class</span>=<span class="st0">"org.apache.commons.dbcp.BasicDataSource"</span> 
<span class="re0">destroy-method</span>=<span class="st0">"close"</span><span class="re2">&gt;</span></span>
<span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"driverClassName"</span> <span class="re0">value</span>=<span class="st0">"org.apache.derby.jdbc.EmbeddedDriver"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"url"</span> <span class="re0">value</span>=<span class="st0">"jdbc:derby:carsales;create=true"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"username"</span> <span class="re0">value</span>=<span class="st0">""</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"password"</span> <span class="re0">value</span>=<span class="st0">""</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/bean<span class="re2">&gt;</span></span></span></pre>
<p>
Alternatively you can configure the data source in your web application
server and reference it from the Spring configuration file as follows:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;bean</span> <span class="re0">id</span>=<span class="st0">"carsalesDataSource"</span> <span class="re0">class</span>=<span class="st0">"org.springframework.jndi.JndiObjectFactoryBean"</span><span class="re2">&gt;</span></span>
<span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"jndiName"</span> <span class="re0">value</span>=<span class="st0">"java:comp/env/jdbc/carsales"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/bean<span class="re2">&gt;</span></span></span></pre>
<p>
The default <acronym title="Uniform Resource Identifier">URI</acronym> (<code>jdbc:derby:carsales;create=true</code>)
will create a database in the root directory where you run the
application from. Alternatively you can specify a fixed path as
follows: <code>jdbc:derby:C:/cep/uidl/db/carsales;create=true</code>.
</p>

<p>
The default configuration will create and export a new database schema
each time the application server is started (or the web application is
restarted). This is defined in the following configuration:
</p>
<pre class="code">&lt;property name="hibernateProperties"&gt;
    &lt;props&gt;
	&lt;prop key="hibernate.dialect"&gt;org.hibernate.dialect.DerbyDialect&lt;/prop&gt;
	&lt;prop key="hibernate.hbm2ddl.auto"&gt;create&lt;/prop&gt;
    &lt;/props&gt;
&lt;/property&gt;
</pre>

<p>The application will automatically populate the database with some
default data if it finds that it is empty. Typically though, after your
first run (when the Derby database is created) you should comment out
the schema export code as follows:
</p>
<pre class="code">&lt;property name="hibernateProperties"&gt;
    &lt;props&gt;
	&lt;prop key="hibernate.dialect"&gt;org.hibernate.dialect.DerbyDialect&lt;/prop&gt;
	&lt;!-- &lt;prop key="hibernate.hbm2ddl.auto"&gt;create&lt;/prop&gt; --&gt;
    &lt;/props&gt;
&lt;/property&gt;
</pre>

<p>Failure to complete this configuration will mean that whenever the
web application is restarted it will be recreated and repopulated with
the default content.
</p>

</div>

<h5><a name="building_uidl" id="building_uidl">Building UIDL</a></h5>
<div class="level5">

<p>
 If you intend to modify or recompile the UIDL browser code, you will need to be able to build the <code>uidl.jar</code>
file. Note that it is very important to sign all the JAR files which
will be loaded when the browser is run as an applet or as a Java Web
Start application. This is typically just <code>uidl.jar</code> and <code>js.jar</code> (Rhino).
</p>

<p>
If you wish to distribute the UIDL browser (or a UIDL application) in a
production environment then it is advisable to sign all the required
JAR files using a proper digital certificate issued from a trusted
certificate authority. The build script (<code>build.xml</code>) can be modified with the appropriate certificate information if required.
</p>

<p>
To generate your own certificate (for local testing) you should use the keytool utility which is included with the Java <acronym title="Java Development Kit">JDK</acronym>. This can be accomplished as follows:
</p>

<p>
<code>keytool -genkey -alias myalias</code>
</p>

<p>
You will then need to answer a feq questions. When you are finished,
make sure you modify the build.xml with the alias and password you used
in the previous step:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;target</span> <span class="re0">name</span>=<span class="st0">"signedjar"</span> <span class="re0">depends</span>=<span class="st0">"jar"</span> <span class="re0">description</span>=<span class="st0">"Create a .jar file from UIDL browser classes"</span><span class="re2">&gt;</span></span>
   <span class="sc3"><span class="re1">&lt;signjar</span> <span class="re0">alias</span>=<span class="st0">"myalias"</span> <span class="re0">storepass</span>=<span class="st0">"mypassword"</span><span class="re2">&gt;</span></span>
        <span class="sc3"><span class="re1">&lt;fileset</span> <span class="re0">dir</span>=<span class="st0">"${outputDir}/"</span> <span class="re0">includes</span>=<span class="st0">"**/*.jar"</span><span class="re2">/&gt;</span></span>
   <span class="sc3"><span class="re1">&lt;/signjar<span class="re2">&gt;</span></span></span>
<span class="sc3"><span class="re1">&lt;/target<span class="re2">&gt;</span></span></span></pre>
<p>
The targets available for building the UIDL browser are as follows:
</p>
<pre class="code">ant -projecthelp
Buildfile: build.xml
Main targets:

 classpathInfo  Display current application classpath
 clean          Delete built files
 compile        Compile core classes
 copyResources  Copies .properties files to classDir
 jar            Create a .jar file from core classes
 signedjar      Create a .jar file from UIDL browser classes

Default target: signedjar
</pre>

<p>
Typically you will compile a new browser by using ”<code>ant signedjar</code>”. This will produce a new UIDL browser library (<code>uidl.jar</code>) in the <code>webapp/browser</code>
directory. In this way, the browser (either running as a Java WebStart
application or as an applet) will pick up the new JAR file the next
time it runs.
</p>

<p>
In order to compile the example applications, a second build script is used. This time the options are as follows:
</p>
<pre class="code">ant -buildfile examples.xml -projecthelp
Buildfile: examples.xml
Main targets:

 classpathInfo   Display current application classpath
 clean           Delete built files
 compile         Compile core classes
 copyResources   Copies resources files to classDir
 jar             Create a .jar file from core classes
 remoteClassJar  Create a .jar file for the remote classes
 war             Create a WAR file to deploy the application

Default target: jar
</pre>

<p>
The default target (jar) will produce a new JAR file with the class files for the examples in the <code>/webapp/WEB-INF/lib</code>
directory. Depending on how you have configured your web application
server, you may need to use the “war” target and redeploy the WAR
archive (containing the new examples JAR) to your application server.
</p>

<p>For some of the remoting examples, the UIDL code needs to have
access to both the Java interfaces for the remote object factories /
facades and the class files for the actual objects which are
transmitted (in serialized form) to the UIDL application (and
subsequently translated into JavaScript objects). Rather than passing
the entire “examples.jar” file to the client, we produce a much lighter
”<code>remoteClasses.jar</code>” which is made available in the <code>/webapp/jar</code> directory. The <code>remoteClassJar</code> target is responsible for producing this file and the classes which it contains are specified in ”<code>/build/remoteInterface.txt</code>”.
</p>

</div>

<h4><a name="uidlthe_browser" id="uidlthe_browser">UIDL: The Browser</a></h4>
<div class="level4">

</div>

<h5><a name="uidl_browser_deployment" id="uidl_browser_deployment">UIDL Browser Deployment</a></h5>
<div class="level5">

<p> To make use of a UIDL based application, end users must run a UIDL
“browser”. This is analogous to a web browser except that it interprets
and renders the UIDL language rather than <acronym title="HyperText Markup Language">HTML</acronym> (actually it has limited support for <acronym title="HyperText Markup Language">HTML</acronym> rendering as well). It could also be considered as a “universal client” for rich internet applications.
</p>

<p>
The size of the browser / universal client is quite small (500Kb - 1Mb
depending on remoting options) and it only needs to be downloaded once
irrespective of the number of UIDL applications with which it is used.
Being Java based, the browser will run on any <acronym title="Operating System">OS</acronym> which supports a recent Java Virtual Machine.
</p>

<p>
In order to simplify the (one time) deployment of the UIDL browser, many options have been made available, including: 
</p>
<ul>
<li class="level1"><div class="li"> Stand alone mode. Typically used by developers, where all Java libraries are statically located on the client machine.</div>
</li>
<li class="level1"><div class="li"> Java Web Start mode. This mode
makes use of the Java Web Start technology introduced in recent
versions of the Sun JRE. Users simply need to click once on the JNLP
file describing the UIDL browser and it will be installed on their
machine. In addition, if updates to the browser are ever required,
these will be transparently loaded by the client each time they run the
browser.</div>
</li>
<li class="level1"><div class="li"> Applet mode. For the most
transparent deployment, the UIDL browser can be embedded within a
standard web browser as a Java applet. Being a signed applet, it will
only need to download the constituent libraries once and will cache
them locally on the client machine. This means that the page containing
the applet will always load quickly. Updates to the browser code will
be delivered transparently to clients running in this mode.</div>
</li>
</ul>

</div>

<h5><a name="the_uidl_browser" id="the_uidl_browser">The UIDL Browser</a></h5>
<div class="level5">

<p>
 The UIDL Browser looks similar to the following picture when run as a Java Web Start application.
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fhowitw1.jpg" class="media" title="http://java.uidl.net/doc/images/howitw1.jpg"><img src="index_files/fetch_002.jpg" class="media" title="java.uidl.net_doc_images_howitw1.jpg" alt="java.uidl.net_doc_images_howitw1.jpg"></a>
</p>

<p>
When a UIDL page is loaded, the body of the UIDL application is displayed in the browser's content area as follows:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fhowitw2.jpg" class="media" title="http://java.uidl.net/doc/images/howitw2.jpg"><img src="index_files/fetch_005.jpg" class="media" title="java.uidl.net_doc_images_howitw2.jpg" alt="java.uidl.net_doc_images_howitw2.jpg"></a>
</p>

<p>
When deployed as a Java WebStart application or Java Applet, one can pass the <acronym title="Uniform Resource Locator">URL</acronym>
of the UIDL application script to the UIDL browser as a parameter and
choose to have the address bar concealed. In this way, the user isn't
presented with an address bar or navigation buttons and the specified
page loads immediately. Compare the application above with that below:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fhowitw3.jpg" class="media" title="http://java.uidl.net/doc/images/howitw3.jpg"><img src="index_files/fetch.jpg" class="media" title="java.uidl.net_doc_images_howitw3.jpg" alt="java.uidl.net_doc_images_howitw3.jpg"></a>
</p>

<p>This mode of deployment is recommended for environments where the
user will only be accessing a single UIDL based application (and
therefore doesn't need the navigation capabilities) or when the UIDL
browser is run as an applet and the users may confuse the <acronym title="HyperText Markup Language">HTML</acronym>
browser's navigation bar with that of the UIDL browser. This mode of
deployment can be thought of as “embedding” the UIDL browser into the
UIDL application.
</p>

</div>

<h5><a name="running_a_uidl_application_with_java_web_start" id="running_a_uidl_application_with_java_web_start">Running a UIDL application with Java Web Start</a></h5>
<div class="level5">

<p> Java Web Start is one of the most convenient ways to run a UIDL
based application. It allows for automatic application updating and
integration with the user's desktop. An example of a Web Start
descriptor (JNLP file) for a UIDL application is as follows
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;?xml</span> <span class="re0">version</span>=<span class="st0">"1.0"</span> <span class="re0">encoding</span>=<span class="st0">"utf-8"</span><span class="re2">?&gt;</span></span>
<span class="sc3"><span class="coMULTI">&lt;!-- JNLP File for UIDL Browser --&gt;</span></span>
<span class="sc3"><span class="re1">&lt;jnlp</span>
  <span class="re0">spec</span>=<span class="st0">"1.0+"</span>
  <span class="re0">codebase</span>=<span class="st0">"http://www.uidl.net/browser/"</span>
  <span class="re0">href</span>=<span class="st0">"uidl.jnlp"</span><span class="re2">&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;information<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;title<span class="re2">&gt;</span></span></span>UIDL Browser<span class="sc3"><span class="re1">&lt;/title<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;vendor<span class="re2">&gt;</span></span></span>www.uidl.net<span class="sc3"><span class="re1">&lt;/vendor<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;homepage</span> <span class="re0">href</span>=<span class="st0">"docs/help.html"</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;description<span class="re2">&gt;</span></span></span>UIDL Browser<span class="sc3"><span class="re1">&lt;/description<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;description</span> <span class="re0">kind</span>=<span class="st0">"short"</span><span class="re2">&gt;</span></span>A browser for displaying rich client
    applications written in the UIDL syntax.<span class="sc3"><span class="re1">&lt;/description<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;icon</span> <span class="re0">href</span>=<span class="st0">"images/logo.jpg"</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;offline-allowed</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;shortcut<span class="re2">&gt;</span></span></span>
      <span class="sc3"><span class="re1">&lt;desktop</span><span class="re2">/&gt;</span></span>
      <span class="sc3"><span class="re1">&lt;menu</span> <span class="re0">submenu</span>=<span class="st0">"UIDL"</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;/shortcut<span class="re2">&gt;</span></span></span>
  <span class="sc3"><span class="re1">&lt;/information<span class="re2">&gt;</span></span></span>
  <span class="sc3"><span class="re1">&lt;security<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;all-permissions</span><span class="re2">/&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;/security<span class="re2">&gt;</span></span></span>
  <span class="sc3"><span class="re1">&lt;resources<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;j2se</span> <span class="re0">version</span>=<span class="st0">"1.3+"</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"uidl.jar"</span> <span class="re0">download</span>=<span class="st0">"eager"</span><span class="re2">/&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"js.jar"</span> <span class="re0">download</span>=<span class="st0">"eager"</span><span class="re2">/&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;/resources<span class="re2">&gt;</span></span></span>
  <span class="sc3"><span class="re1">&lt;application-desc</span> <span class="re0">main-class</span>=<span class="st0">"net.uidl.Browser"</span><span class="re2">&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;/application-desc<span class="re2">&gt;</span></span></span>
<span class="sc3"><span class="re1">&lt;/jnlp<span class="re2">&gt;</span></span></span></pre>
<p>
As with the applet version of the UIDL browser, if you are going to be using <a href="#spring_remoting" title="uidldocumentation ↵" class="wikilink1">Spring remoting</a>, you will need to include some extra libraries, as follows:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"js.jar"</span> <span class="re0">download</span>=<span class="st0">"eager"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"spring-client.jar"</span> <span class="re0">download</span>=<span class="st0">"lazy"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/resources<span class="re2">&gt;</span></span></span></pre>
<p>
If you would like the applet to automatically load a UIDL page (even from a different server) and <a href="http://java.uidl.net/doc/images/howitw3.jpg" class="urlextern" title="http://java.uidl.net/doc/images/howitw3.jpg" rel="nofollow">not display a navigation bar</a>, then you will need to include an extra  couple of parameters as follows:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;application-desc</span> <span class="re0">main-class</span>=<span class="st0">"net.uidl.Browser"</span><span class="re2">&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;argument<span class="re2">&gt;</span></span></span>http://localhost:8080/uidl/admin/admin.uidl<span class="sc3"><span class="re1">&lt;/argument<span class="re2">&gt;</span></span></span>
  <span class="sc3"><span class="re1">&lt;argument<span class="re2">&gt;</span></span></span>false<span class="sc3"><span class="re1">&lt;/argument<span class="re2">&gt;</span></span></span>
<span class="sc3"><span class="re1">&lt;/application-desc<span class="re2">&gt;</span></span></span></pre>
<p>Finally, if you would like to load some extra (client side) Java
libraries which the UIDL application will make use of, then these can
be added to the applet classpath as follows:
</p>
<pre class="code xml">  <span class="sc3"><span class="re1">&lt;j2se</span> <span class="re0">version</span>=<span class="st0">"1.3+"</span><span class="re2">/&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"uidl.jar"</span> <span class="re0">download</span>=<span class="st0">"eager"</span><span class="re2">/&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"js.jar"</span> <span class="re0">download</span>=<span class="st0">"eager"</span><span class="re2">/&gt;</span></span>
  <span class="sc3"><span class="re1">&lt;jar</span> <span class="re0">href</span>=<span class="st0">"TableLayout.jar"</span> <span class="re0">download</span>=<span class="st0">"lazy"</span><span class="re2">/&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/resources<span class="re2">&gt;</span></span></span></pre>
<p>
Note that external libraries can also be loaded dynamically from within UIDL scripts as follows:
</p>

<p>
<code>browser.loadRemoteLibrary(“myclientlib.jar”);</code>
</p>

<p>Loading libraries from within the JNLP descriptor has the advantage
of caching the JAR file and eliminates some security issues when using
signed JAR files, although it is advised to load libraries from within
scripts wherever possible to place the maximum amount of logic within
the script itself and reduce external dependencies.
</p>

</div>

<h5><a name="embedding_the_uidl_browser_in_an_applet" id="embedding_the_uidl_browser_in_an_applet">Embedding the UIDL Browser in an Applet</a></h5>
<div class="level5">

<p>
 To embed the UIDL browser in an applet, you will need to include the following code in an <acronym title="HyperText Markup Language">HTML</acronym> page:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;applet</span> <span class="re0">name</span>=<span class="st0">"uidlApplet"</span> <span class="re0">codebase</span>=<span class="st0">"."</span>
        <span class="re0">archive</span>=<span class="st0">"uidl.jar,js.jar"</span>
        <span class="re0">code</span>=<span class="st0">"net.uidl.BrowserApplet.class"</span> <span class="re0">width</span>=<span class="st0">"100%"</span> <span class="re0">height</span>=<span class="st0">"95%"</span> <span class="re0">alt</span>=<span class="st0">"No applet"</span><span class="re2">&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/applet<span class="re2">&gt;</span></span></span></pre>
<p>If you would like the applet to automatically load a UIDL page (even
from a different server) and not display a navigation bar, then simply
include the address of the page as a parameter to the applet as
follows:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;applet</span> <span class="re0">name</span>=<span class="st0">"uidlApplet"</span> <span class="re0">codebase</span>=<span class="st0">"."</span>
        <span class="re0">archive</span>=<span class="st0">"uidl.jar,js.jar"</span>
        <span class="re0">code</span>=<span class="st0">"net.uidl.BrowserApplet.class"</span> <span class="re0">width</span>=<span class="st0">"100%"</span> <span class="re0">height</span>=<span class="st0">"95%"</span> <span class="re0">alt</span>=<span class="st0">"No applet"</span><span class="re2">&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;param</span> <span class="re0">name</span>=<span class="st0">"url"</span> <span class="re0">value</span>=<span class="st0">"http://www.uidl.net/example/carsales.uidl"</span><span class="re2">&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;param</span> <span class="re0">name</span>=<span class="st0">"addressBar"</span> <span class="re0">value</span>=<span class="st0">"false"</span><span class="re2">&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/applet<span class="re2">&gt;</span></span></span></pre>
<p>Finally, if you would like to load some extra (client side) Java
libraries which the UIDL application will make use of, then these can
be added to the applet classpath as follows:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;applet</span> <span class="re0">name</span>=<span class="st0">"uidlApplet"</span> <span class="re0">codebase</span>=<span class="st0">"."</span>
        <span class="re0">archive</span>=<span class="st0">"uidl.jar,js.jar,myclientlib.jar"</span>
        <span class="re0">code</span>=<span class="st0">"net.uidl.BrowserApplet.class"</span> <span class="re0">width</span>=<span class="st0">"100%"</span> <span class="re0">height</span>=<span class="st0">"95%"</span> <span class="re0">alt</span>=<span class="st0">"No applet"</span><span class="re2">&gt;</span></span>
<span class="sc3"><span class="re1">&lt;/applet<span class="re2">&gt;</span></span></span></pre>
<p>
Note that external libraries can also be loaded dynamically from within UIDL scripts as follows:
</p>

<p>
<code>browser.loadRemoteLibrary(“myclientlib.jar”);</code>
</p>

<p>Loading libraries from within applet code has the advantage of
caching the JAR file and eliminates some security issues when using
signed JAR files, although it is advised to load libraries from within
scripts wherever possible to place the maximum amount of logic within
the script itself and reduce external dependencies.
</p>

</div>

<h4><a name="writing_uidl_applications" id="writing_uidl_applications">Writing UIDL Applications</a></h4>
<div class="level4">

</div>

<h5><a name="introduction1" id="introduction1">Introduction</a></h5>
<div class="level5">

<p> A UIDL application is basically a JavaScript application which has
the possibility of accessing core Java libraries. If you consider
JavaScript running within a standard browser, it's power is rather
limited as it can only interact with the Document Object Model (<acronym title="Document Object Model">DOM</acronym>) of the <acronym title="HyperText Markup Language">HTML</acronym> page and has no way of interacting with the server (short of recent <acronym title="Asynchronous JavaScript and XML">AJAX</acronym>
extensions). This has relegated JavaScript to a language which has been
used for basic tasks such as validating user input or creating dynamic
menus or collapsible paragraphs.
</p>

<p>By proving JavaScript with access to the windowing system of the
host operating system and (via Java Swing) and with access to server
based objects (via remoting) very complex and rich applications can be
constructed in JavaScript / ECMA script.
</p>

</div>

<h5><a name="the_javascript_interpreter" id="the_javascript_interpreter">The JavaScript Interpreter</a></h5>
<div class="level5">

<p> Rather than writing a JavaScript interpreter, the UIDL browser
environment makes use of the Mozilla “Rhino” interpreter. Rhino is a
JavaScript interpreter written in Java. The use of a Java based
JavaScript interpreter is important for two reasons: </p>
<ul>
<li class="level1"><div class="li"> it provides us with a client platform which will run on most operating systems</div>
</li>
<li class="level1"><div class="li"> it provides easy access to Java objects, allowing for easy expansion of capabilities and interfacing with server environments</div>
</li>
</ul>

<p>
 More information about Rhino can be found at <a href="http://www.mozilla.org/rhino/" class="urlextern" title="http://www.mozilla.org/rhino/" rel="nofollow">here</a>.
</p>

</div>

<h5><a name="core_uidl_browser_objects" id="core_uidl_browser_objects">Core UIDL Browser Objects</a></h5>
<div class="level5">

<p> Just as a typical web browser provides applications with a set of
core objects (such as window, history, etc) the UIDL browser provides
hosted applications with a set of standard objects and functions. In
addition to these “core” objects, any standard library can be used,
provided it is made available to the browsers JVM.
</p>

<p>
The core UIDL Browser objects are the following: 
</p>
<ul>
<li class="level1"><div class="li"> <code>browser</code>: the browser itself. Provides access to the following functions:</div>
<ul>
<li class="level2"><div class="li"> <code>include</code>: loads one UIDL page from another (dynamically)</div>
</li>
<li class="level2"><div class="li"> <code>loadRemoteLibrary</code>: dynamically loads a JAR file from the server</div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <code>frame</code>: an empty JInternalFrame in which the application can use to construct its UI.</div>
</li>
<li class="level1"><div class="li"> <code>hostName</code>: the name of the server from where the UIDL script was loaded</div>
</li>
<li class="level1"><div class="li"> <code>hostPort</code>: the port of the server from where the UIDL script was loaded</div>
</li>
<li class="level1"><div class="li"> <code>hostPrefix</code>: the full <acronym title="Uniform Resource Identifier">URI</acronym> of the directory from which the UIDL script was loaded</div>
</li>
</ul>

</div>

<h5><a name="importing_java_packages" id="importing_java_packages">Importing Java Packages</a></h5>
<div class="level5">

<p>
 Java packages may be imported by creating aliases as follows:
</p>
<pre class="code javascript">Event = java.<span class="me1">awt</span>.<span class="me1">event</span>;
Awt = java.<span class="me1">awt</span>;
Lang = java.<span class="me1">lang</span>;
Util = java.<span class="me1">util</span>;
Swing = Packages.<span class="me1">javax</span>.<span class="me1">swing</span>;
Spring = Packages.<span class="me1">org</span>.<span class="me1">springframework</span>;</pre>
<p>Note that standard java libraries don't require a “Packages” prefix.
Once an alias has been created, new objects may be instantiated as
follows:
</p>

<p>
<code>var button = new Swing.JButton();</code>
</p>

<p>
Alternatively, you can create an alias for a JButton directly as follows:
</p>

<p>
<code>JButton = Swing.JButton;</code>
</p>

<p>
In which case the code to create a new button would be:
</p>

<p>
<code>button = new JButton();</code>
</p>

</div>

<h5><a name="organizing_code" id="organizing_code">Organizing Code</a></h5>
<div class="level5">

<p>
 As UIDL applications get more complicated, they can grow to the point where a single ”<code>.uidl</code>”
file is not sufficient to handle the application code. This is where
the “import” function of the browser object becomes important. Imaging
that we had the above package definitions in a separate file called ”<code>packages.uidl</code>”. In this case, we could have a second UIDL script in which we made use of the first script as follows:
</p>
<pre class="code javascript">browser.<span class="me1">include</span><span class="br0">(</span><span class="st0">"packages.uidl"</span><span class="br0">)</span>;
button = <span class="kw2">new</span> JButton<span class="br0">(</span><span class="br0">)</span>;</pre>
</div>

<h5><a name="creating_a_simple_application" id="creating_a_simple_application">Creating a Simple Application</a></h5>
<div class="level5">

<p>
 A simple UIDL application is given below:
</p>
<pre class="code javascript">Awt = java.<span class="me1">awt</span>;
Swing = Packages.<span class="me1">javax</span>.<span class="me1">swing</span>;
JLabel = Swing.<span class="me1">JLabel</span>;
&nbsp;
frame.<span class="me1">setLayout</span><span class="br0">(</span><span class="kw2">new</span> Awt.<span class="me1">BorderLayout</span><span class="br0">(</span><span class="br0">)</span><span class="br0">)</span>;
frame.<span class="me1">setTitle</span><span class="br0">(</span><span class="st0">"Very Simple Administration"</span><span class="br0">)</span>;
<span class="kw2">var</span> l = <span class="kw2">new</span> JLabel<span class="br0">(</span>
    <span class="st0">"&lt;html&gt;&lt;p align='center'&gt;Welcome to a&lt;br&gt;"</span> +
    <span class="st0">"&lt;font size='7' color='green'&gt;VERY SIMPLE&lt;/font&gt;&lt;br&gt;&lt;br&gt;"</span> +
    <span class="st0">"UIDL Application&lt;/p&gt;&lt;/html&gt;"</span><span class="br0">)</span>;
l.<span class="me1">setHorizontalAlignment</span><span class="br0">(</span>Swing.<span class="me1">SwingConstants</span>.<span class="me1">CENTER</span><span class="br0">)</span>;
frame.<span class="me1">add</span><span class="br0">(</span>l<span class="br0">)</span>;</pre>
<p>
Which will render as follows:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fapplic4.jpg" class="media" title="http://java.uidl.net/doc/images/applic4.jpg"><img src="index_files/fetch_004.jpg" class="media" title="java.uidl.net_doc_images_applic4.jpg" alt="java.uidl.net_doc_images_applic4.jpg"></a>
</p>

</div>

<h5><a name="creating_a_more_complex_application" id="creating_a_more_complex_application">Creating a more complex Application</a></h5>
<div class="level5">

<p> A more complex currency converter application (albeit slightly out
of date) is shown below. Note that in a real version, remoting would be
used to perform the currency conversion on the server, thereby using
the most up to date exchange rates.
</p>
<pre class="code javascript">Swing = Packages.<span class="me1">javax</span>.<span class="me1">swing</span>;
Event = java.<span class="me1">awt</span>.<span class="me1">event</span>;
Awt = java.<span class="me1">awt</span>;
Lang = java.<span class="me1">lang</span>;
Util = java.<span class="me1">util</span>;
&nbsp;
System = Lang.<span class="me1">System</span>;
JPanel = Swing.<span class="me1">JPanel</span>;
JButton = Swing.<span class="me1">JButton</span>;
&nbsp;
<span class="kw2">var</span> labelPrefix = <span class="st0">"Amount in Italian lira: "</span>;
&nbsp;
<span class="kw2">function</span> aboutAction<span class="br0">(</span>evt<span class="br0">)</span>
<span class="br0">{</span>
    Swing.<span class="me1">JOptionPane</span>.<span class="me1">showMessageDialog</span><span class="br0">(</span>frame, <span class="st0">"Eggs aren't supposed to be green."</span><span class="br0">)</span>;
<span class="br0">}</span>
&nbsp;
<span class="kw2">function</span> quitAction<span class="br0">(</span>evt<span class="br0">)</span>
<span class="br0">{</span>
    System.<span class="me1">exit</span><span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span>;
<span class="br0">}</span>
&nbsp;
<span class="kw2">function</span> createComponents<span class="br0">(</span><span class="br0">)</span>
<span class="br0">{</span>
    textField = <span class="kw2">new</span> Swing.<span class="me1">JTextField</span><span class="br0">(</span><span class="nu0">20</span><span class="br0">)</span>;
&nbsp;
    label = <span class="kw2">new</span> Swing.<span class="me1">JLabel</span><span class="br0">(</span>labelPrefix + <span class="st0">"0"</span><span class="br0">)</span>;
    button = <span class="kw2">new</span> JButton<span class="br0">(</span><span class="st0">"Convert dollars to lira"</span><span class="br0">)</span>;
    button.<span class="me1">setMnemonic</span><span class="br0">(</span>Event.<span class="me1">KeyEvent</span>.<span class="me1">VK_I</span><span class="br0">)</span>;
    button.<span class="me1">addActionListener</span><span class="br0">(</span>buttonAction<span class="br0">)</span>
    label.<span class="me1">setLabelFor</span><span class="br0">(</span>button<span class="br0">)</span>;
&nbsp;
    pane = <span class="kw2">new</span> JPanel<span class="br0">(</span><span class="br0">)</span>;
    pane.<span class="me1">setBorder</span><span class="br0">(</span>Swing.<span class="me1">BorderFactory</span>.<span class="me1">createEmptyBorder</span><span class="br0">(</span><span class="nu0">30</span>, <span class="nu0">30</span>, <span class="nu0">10</span>, <span class="nu0">30</span><span class="br0">)</span><span class="br0">)</span>;
    pane.<span class="me1">setLayout</span><span class="br0">(</span><span class="kw2">new</span> Awt.<span class="me1">GridLayout</span><span class="br0">(</span><span class="nu0">0</span>, <span class="nu0">1</span><span class="br0">)</span><span class="br0">)</span>;
    pane.<span class="me1">add</span><span class="br0">(</span>textField<span class="br0">)</span>;
    pane.<span class="me1">add</span><span class="br0">(</span>button<span class="br0">)</span>;
    pane.<span class="me1">add</span><span class="br0">(</span>label<span class="br0">)</span>;
&nbsp;
    <span class="kw1">return</span> pane;
<span class="br0">}</span>
&nbsp;
<span class="kw2">function</span> createMenuBar<span class="br0">(</span><span class="br0">)</span>
<span class="br0">{</span>
    jMenuBar = <span class="kw2">new</span> Swing.<span class="me1">JMenuBar</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuFile = <span class="kw2">new</span> Swing.<span class="me1">JMenu</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuFile.<span class="me1">setText</span><span class="br0">(</span><span class="st0">"File"</span><span class="br0">)</span>;
    jMenuFileExit = <span class="kw2">new</span> Swing.<span class="me1">JMenuItem</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuFileExit.<span class="me1">setText</span><span class="br0">(</span><span class="st0">"Exit"</span><span class="br0">)</span>;
    jMenuFileExit.<span class="me1">addActionListener</span><span class="br0">(</span>quitAction<span class="br0">)</span>;
    jMenuHelp = <span class="kw2">new</span> Swing.<span class="me1">JMenu</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuHelp.<span class="me1">setText</span><span class="br0">(</span><span class="st0">"Help"</span><span class="br0">)</span>;
    jMenuHelpAbout = <span class="kw2">new</span> Swing.<span class="me1">JMenuItem</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuHelpAbout.<span class="me1">setText</span><span class="br0">(</span><span class="st0">"About"</span><span class="br0">)</span>;
    jMenuHelpAbout.<span class="me1">addActionListener</span><span class="br0">(</span>aboutAction<span class="br0">)</span>;
&nbsp;
    appToolbar = <span class="kw2">new</span> Swing.<span class="me1">JToolBar</span><span class="br0">(</span><span class="br0">)</span>;
    jMenuFile.<span class="me1">add</span><span class="br0">(</span>jMenuFileExit<span class="br0">)</span>;
    jMenuHelp.<span class="me1">add</span><span class="br0">(</span>jMenuHelpAbout<span class="br0">)</span>;
    jMenuBar.<span class="me1">add</span><span class="br0">(</span>jMenuFile<span class="br0">)</span>;
    jMenuBar.<span class="me1">add</span><span class="br0">(</span>jMenuHelp<span class="br0">)</span>;
&nbsp;
    <span class="kw1">return</span> jMenuBar;
<span class="br0">}</span>
&nbsp;
<span class="kw2">function</span> buttonAction<span class="br0">(</span>evt<span class="br0">)</span>
<span class="br0">{</span>
    inp = textField.<span class="me1">getText</span><span class="br0">(</span><span class="br0">)</span>;
    amount = inp * <span class="nu0">1000</span>;
&nbsp;
    label.<span class="me1">setText</span><span class="br0">(</span>labelPrefix + amount<span class="br0">)</span>;
<span class="br0">}</span>
&nbsp;
contents = createComponents<span class="br0">(</span><span class="br0">)</span>;
frame.<span class="me1">setLayout</span><span class="br0">(</span><span class="kw2">new</span> Awt.<span class="me1">FlowLayout</span><span class="br0">(</span><span class="br0">)</span><span class="br0">)</span>;
frame.<span class="me1">add</span><span class="br0">(</span>contents<span class="br0">)</span>;
menuBar = createMenuBar<span class="br0">(</span><span class="br0">)</span>;
frame.<span class="me1">setJMenuBar</span><span class="br0">(</span>menuBar<span class="br0">)</span>;</pre>
<p>
This application renders as follows:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fapplic7.jpg" class="media" title="http://java.uidl.net/doc/images/applic7.jpg"><img src="index_files/fetch_007.jpg" class="media" title="java.uidl.net_doc_images_applic7.jpg" alt="java.uidl.net_doc_images_applic7.jpg"></a>
</p>

</div>

<h5><a name="debugging_uidl_applications" id="debugging_uidl_applications">Debugging UIDL applications</a></h5>
<div class="level5">

<p> The UIDL browser (when not running in embedded mode) has the
ability to display the source of the current application along with any
errors or console output. This is invaluable to determining the root
cause of a UIDL application error. See below:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fapplic6.jpg" class="media" title="http://java.uidl.net/doc/images/applic6.jpg"><img src="index_files/fetch_003.jpg" class="media" title="java.uidl.net_doc_images_applic6.jpg" alt="java.uidl.net_doc_images_applic6.jpg"></a>
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2Fapplic5.jpg" class="media" title="http://java.uidl.net/doc/images/applic5.jpg"><img src="index_files/fetch_006.jpg" class="media" title="java.uidl.net_doc_images_applic5.jpg" alt="java.uidl.net_doc_images_applic5.jpg"></a>
</p>

</div>

<h5><a name="other_scripting_resources" id="other_scripting_resources">Other Scripting Resources</a></h5>
<div class="level5">

<p>
 More information about JavaScript scripting of Java objects can be found in the <a href="http://www.mozilla.org/rhino/doc.html" class="urlextern" title="http://www.mozilla.org/rhino/doc.html" rel="nofollow">Rhino documentation</a>.
</p>

</div>

<h4><a name="uidl_remoting" id="uidl_remoting">UIDL Remoting</a></h4>
<div class="level4">

</div>

<h5><a name="introduction2" id="introduction2">Introduction</a></h5>
<div class="level5">

<p>
 Writing rich <acronym title="Graphical User Interface">GUI</acronym>
client applications wouldn't be extremely useful if they had no way of
communicating with a server for dynamic data updates. In a traditional
web application, when new data is required, a new <acronym title="HyperText Markup Language">HTML</acronym>
page is generated from the server with the relevant information. This
model is both slow for the user and cumbersome for the developer.
</p>

<p>In a UIDL application, the user interface description is downloaded
and rendered once UIDL page is loaded. As the user interacts with the
UI data may be required to be updated from the server. The mechanism
which UIDL makes available for this type of interaction is that of
client side proxies: JavaScript objects which share similar methods to
that of their server side counterparts. The proxies are responsible for
marshalling the data to server and making the return object available
to the client as a native JavaScript object.
</p>

<p>Using this principle, remote user interfaces can be developed
extremely easily for server applications as the existing server side
objects can be transparently made available to clients with little or
no modification to existing code.
</p>

<p>
UIDL currently supports two forms of remoting: JSON-<acronym title="Remote Procedure Call">RPC</acronym> and Spring remoting.
</p>

</div>

<h5><a name="json-rpc" id="json-rpc">JSON-RPC</a></h5>
<div class="level5">

<p>
 <a href="http://jabsorb.org/" class="urlextern" title="http://jabsorb.org/" rel="nofollow">JSON-RPC</a> in a remote object protocol based on the JavaScript Object Notation (<a href="http://www.crockford.com/JSON/" class="urlextern" title="http://www.crockford.com/JSON/" rel="nofollow">JSON</a>).
In this protocol, method invocations performed on client side
JavaScript objects are transmitted to the server in JSON format. From
there, a server side service invoker is responsible for controlling
access rights and performing the method invocations on the actual
server based objects. The result is then converted to JSON, transmitted
back to the client and desterilized into a JavaScript object.
</p>

<p>The advantage of using this protocol with UIDL is that it is
extremely flexible: no Java class libraries need to be transmitted to
the client to support the corresponding implementations which reside on
the server (as would be needed with alternative protocols such as RMI).
This allows client memory footprints to remain small and allows UIDL
scripts to be relatively robust to changes in server side objects (code
will only break if method signatures change dramatically).
</p>

<p>
To use JSON <acronym title="Remote Procedure Call">RPC</acronym>,
the server must be modified to expose any objects which must be
accessible by the client. This can be done inside a simple servlet or
(better still) a servlet listener. The code to register an object
should be similar to the following:
</p>
<pre class="code javascript">Hello hello = <span class="kw2">new</span> Hello<span class="br0">(</span><span class="br0">)</span>;
JSONRPCBridge.<span class="me1">getGlobalBridge</span><span class="br0">(</span><span class="br0">)</span>.<span class="me1">registerObject</span><span class="br0">(</span><span class="st0">"hello"</span>, hello<span class="br0">)</span>;</pre>
<p>
This will make the “Hello” object accessible from UIDL clients using the JSON <acronym title="Remote Procedure Call">RPC</acronym> protocol.
</p>

<p>
Alternatively, the ”<code>net.uidl.util.JsonRpcExporter</code>” service can be used to register Spring hosted objects. This is the technique employed by the bundled example applications.
</p>

<p>
In order to access the object from a UIDL script, the following code can be used:
</p>
<pre class="code javascript">jsonrpc = <span class="kw2">new</span> JSONRpcClient<span class="br0">(</span>hostPrefix + <span class="st0">"JSON-RPC"</span><span class="br0">)</span>;
message = jsonrpc.<span class="me1">hello</span>.<span class="me1">sayHello</span><span class="br0">(</span><span class="st0">"Dominic"</span><span class="br0">)</span>;</pre>
<p>For requests which might take some time, a callback can be used
which will be called with the return parameter once the method
invocation is complete. In this case, the code would look similar to
the following:
</p>
<pre class="code javascript"><span class="kw2">function</span> callback<span class="br0">(</span>result, exception<span class="br0">)</span>
<span class="br0">{</span>
    System.<span class="me1">out</span>.<span class="me1">println</span><span class="br0">(</span>result<span class="br0">)</span>;
<span class="br0">}</span>
&nbsp;
jsonrpc = <span class="kw2">new</span> JSONRpcClient<span class="br0">(</span>hostPrefix + <span class="st0">"JSON-RPC"</span><span class="br0">)</span>;
jsonrpc.<span class="me1">hello</span>.<span class="me1">sayHello</span><span class="br0">(</span>callback, <span class="st0">"Dominic"</span><span class="br0">)</span>;</pre>
<p>
The JSON <acronym title="Remote Procedure Call">RPC</acronym>
protocol does have some disadvantages in that it is less efficient for
requests which return large amounts of data (such as collections of
objects) due to the expense of converting Java objects to JavaScript
notation. In addition, complex objects which are returned via the
JSONRpcCilent are not directly usable in UIDL scripts. They can be
passed back to the server and referenced, although their internal
properties remain opaque.
</p>

<p>
To address this last concern and to increase the performance somewhat, a native Java implementation of the JSON <acronym title="Remote Procedure Call">RPC</acronym>
client can be used (the afore mentioned JSONRpcCilent is implemented in
JavaScript). The configuration for this second approach is identical on
the server, although the client code should be implemented as follows:
</p>
<pre class="code javascript"><span class="co1">// Libraries for json-rpc-client</span>
browser.<span class="me1">loadRemoteLibrary</span><span class="br0">(</span><span class="st0">"../jar/jabsorb.jar"</span><span class="br0">)</span>;
browser.<span class="me1">loadRemoteLibrary</span><span class="br0">(</span><span class="st0">"../jar/slf4j-api.jar"</span><span class="br0">)</span>;
browser.<span class="me1">loadRemoteLibrary</span><span class="br0">(</span><span class="st0">"../jar/slf4j-jdk14.jar"</span><span class="br0">)</span>;
browser.<span class="me1">include</span><span class="br0">(</span><span class="st0">"packages.uidl"</span><span class="br0">)</span>;
&nbsp;
<span class="kw2">var</span> hostRoot = <span class="st0">"http://"</span> + hostName + <span class="st0">":"</span> + hostPort + <span class="st0">"/uidl/"</span>;
JsonRpc = Packages.<span class="me1">org</span>.<span class="me1">jabsorb</span>.<span class="me1">client</span>;
<span class="kw2">var</span> session = JsonRpc.<span class="me1">TransportRegistry</span>.<span class="me1">i</span><span class="br0">(</span><span class="br0">)</span>.<span class="me1">createSession</span><span class="br0">(</span>hostRoot + <span class="st0">"JSON-RPC"</span><span class="br0">)</span>;
client = <span class="kw2">new</span> JsonRpc.<span class="me1">Client</span><span class="br0">(</span>session<span class="br0">)</span>;
<span class="kw2">var</span> userManager = client.<span class="me1">openProxy</span><span class="br0">(</span><span class="st0">"userManager"</span>, Uidl.<span class="me1">example</span>.<span class="me1">UserManager</span><span class="br0">)</span>;</pre>
<p>
Basically, the UIDL browser will require the help of several external Java libraries to make use of the JSON-<acronym title="Remote Procedure Call">RPC</acronym> Java client. Once we have constructed a “client” object, it is trivial to make calls to any services exposed on the server:
</p>
<pre class="code javascript"><span class="kw2">var</span> userManager = client.<span class="me1">openProxy</span><span class="br0">(</span><span class="st0">"userManager"</span>, Uidl.<span class="me1">example</span>.<span class="me1">UserManager</span><span class="br0">)</span>;
<span class="kw2">var</span> users = userManager.<span class="me1">getUsers</span><span class="br0">(</span><span class="br0">)</span>;
...</pre>
<p>The disadvantage of this approach (over the native JavaScript
variant) is that the UIDL browser must have access to the class files
representing the server side interfaces (e.g. UserManaer) and for any
serialized objects (e.g. User). This requires more coordination as we
need to ensure that whenever these files are modified on the server, we
make the corresponding remote interfaces (a sub-set of the server
files) available to the client. See the remoteClassJar target in the
build section for one way of doing this efficiently.
</p>

</div>

<h5><a name="spring_remoting" id="spring_remoting">Spring Remoting</a></h5>
<div class="level5">

<p>
 As noted in the previous section, JSON <acronym title="Remote Procedure Call">RPC</acronym>
is not the most efficient protocol for function calls which result in
large volumes of data. For this reason, UIDL supports a second form of
remoting: Spring Remoting from the Spring micro container environment.
At this point it must be pointed out that UIDL can actually use any
Java remote object protocol (e.g. RMI, CORBA, etc) thanks to the fact
that it can access transparently native Java libraries. The reason why
Spring remoting is considered to be a “first class citizen” with
respect to its support in UIDL is twofold: </p>
<ul>
<li class="level1"><div class="li"> It is considered that Spring
provides a very robust environment for developing enterprise Java
applications and therefore its use in conjunction with UIDL is
encouraged. In fact, it is proposed that UIDL + Spring + Hibernate
provides an extremely powerful and flexible way of producing scalable
enterprise applications. See the CarSales example for proof of this.</div>
</li>
</ul>
<ul>
<li class="level1"><div class="li"> Spring remoting creates dynamic
proxies. The intent of UIDL is to reduce the amount of Java code on the
client and supplant it with more flexible JavaScript (otherwise, why
not just use applets?). Whilst RMI requires the use of stubs which need
to be delivered to the client and recompiled whenever the host objects
are modified, Spring remoting creates these stubs (or proxies)
dynamically.</div>
</li>
</ul>

<p> Once a Spring method invocation has returned, the resultant object
can be made available to the enclosing UIDL script thanks to the built
in Java access capabilities of the Rhino interpreter. Note that the
Java interfaces for the remote objects must still be available to the
client as do any parameters which are comprised of non-standard
objects. The task of dynamically downloading a Java library containing
these “client helper classes” is facilitated thanks to the ability of
the UIDL browser to download Java libraries at runtime from within UIDL
scripts. Ant scripts should be developed to produce Jar files
containing only those classes which will be required by the client
(again, only interfaces and custom parameters).
</p>

<p>To use Spring remoting from within a UIDL script, one must first
load any class files for the remote objects and interfaces and
initialize the Spring context for the client. This is done as follows:
</p>
<pre class="code javascript">browser.<span class="me1">loadRemoteLibrary</span><span class="br0">(</span><span class="st0">"../jar/remoteClasses.jar"</span><span class="br0">)</span>;
<span class="kw2">var</span> helper = <span class="kw2">new</span> Uidl.<span class="me1">SpringHelper</span><span class="br0">(</span>hostName, hostPort, hostPrefix<span class="br0">)</span>;
<span class="kw2">var</span> context = helper.<span class="me1">loadRemoteConfig</span><span class="br0">(</span><span class="st0">"applicationContext.xml"</span><span class="br0">)</span>;</pre>
<p>This will load a configuration file from the server (from the same
directory from where the UIDL script was loaded) which would look
similar to the following:
</p>
<pre class="code xml"><span class="sc3"><span class="re1">&lt;?xml</span> <span class="re0">version</span>=<span class="st0">"1.0"</span> <span class="re0">encoding</span>=<span class="st0">"UTF-8"</span><span class="re2">?&gt;</span></span>
<span class="sc0">&lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"&gt;</span>
&nbsp;
<span class="sc3"><span class="re1">&lt;beans<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;bean</span> <span class="re0">id</span>=<span class="st0">"userManager"</span>
          <span class="re0">class</span>=<span class="st0">"org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean"</span><span class="re2">&gt;</span></span>
        <span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"serviceUrl"</span><span class="re2">&gt;</span></span>
            <span class="sc3"><span class="re1">&lt;value<span class="re2">&gt;</span></span></span>http://${server}:${port}/uidl/remote/userManager<span class="sc3"><span class="re1">&lt;/value<span class="re2">&gt;</span></span></span>
        <span class="sc3"><span class="re1">&lt;/property<span class="re2">&gt;</span></span></span>
        <span class="sc3"><span class="re1">&lt;property</span> <span class="re0">name</span>=<span class="st0">"serviceInterface"</span><span class="re2">&gt;</span></span>
            <span class="sc3"><span class="re1">&lt;value<span class="re2">&gt;</span></span></span>net.uidl.example.UserManager<span class="sc3"><span class="re1">&lt;/value<span class="re2">&gt;</span></span></span>
        <span class="sc3"><span class="re1">&lt;/property<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;/bean<span class="re2">&gt;</span></span></span>
	.
	.
<span class="sc3"><span class="re1">&lt;/beans<span class="re2">&gt;</span></span></span></pre>
<p>
This “userManager” bean would have been exported on the server using a “HttpInvokerServiceExporter”. See the relevant <a href="http://static.springframework.org/spring/docs/2.5.x/reference/remoting.html" class="urlextern" title="http://static.springframework.org/spring/docs/2.5.x/reference/remoting.html" rel="nofollow">Spring remoting documentation</a> for further information about exporting objects / services to make them available via <acronym title="Hyper Text Transfer Protocol">HTTP</acronym> invocation.
</p>

<p>
Once the Spring context has been initialized on the client, accessing server side resources is straightforward:
</p>
<pre class="code javascript">userManager = context.<span class="me1">getBean</span><span class="br0">(</span><span class="st0">"userManager"</span><span class="br0">)</span>;
<span class="kw2">var</span> users = userManager.<span class="me1">getUsers</span><span class="br0">(</span><span class="br0">)</span>;
<span class="kw1">for</span> <span class="br0">(</span><span class="kw2">var</span> i=<span class="nu0">0</span>; i&lt;users.<span class="me1">size</span><span class="br0">(</span><span class="br0">)</span>; i++<span class="br0">)</span>
<span class="br0">{</span>
    System.<span class="me1">out</span>.<span class="me1">println</span><span class="br0">(</span><span class="st0">"User name: "</span> + users.<span class="me1">get</span><span class="br0">(</span>i<span class="br0">)</span>.<span class="me1">getUserName</span><span class="br0">(</span><span class="br0">)</span><span class="br0">)</span>;
<span class="br0">}</span></pre>
<p>To make use of Spring remoting, you will need a certain degree of
knowledge of the Spring platform. You are encouraged to have a look at
the <a href="http://static.springframework.org/spring/docs/2.5.x/reference/index.html" class="urlextern" title="http://static.springframework.org/spring/docs/2.5.x/reference/index.html" rel="nofollow">Spring documentation</a> for further information.
</p>

<p>
As with the Java implementation of JSON-<acronym title="Remote Procedure Call">RPC</acronym>,
the disadvantage of this approach is that the UIDL browser must have
access to the class files representing the server side interfaces.
</p>

</div>

<h5><a name="the_carsales_sample_application" id="the_carsales_sample_application">The "CarSales" Sample Application</a></h5>
<div class="level5">

<p> The “CarSales” example application is intended as a showcase for
UIDL technology. It uses a combination of Spring and Hibernate on the
server side to implement an application which manages customer's
automotive preferences. The database schema for the example is
presented below:
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2FdbSchema.GIF" class="media" title="http://java.uidl.net/doc/images/dbSchema.GIF"><img src="index_files/fetch_002.gif" class="media" alt=""></a>
</p>

<p>There is a one to one correspondence between the Java objects and
their respective tables. All relationships are managed using EJB 3
persistence annotations and the entire database schema can be
regenerated at any time directly from the object model. The association
tables (e.g. customer_make) are generated automatically and are
required for N:N mappings. Obviously these tables don't directly map to
any Java objects.
</p>

<p>To run the CarSales application, first ensure that your database is
configured correctly and then simply point your UIDL browser at the
CarSales example <acronym title="Uniform Resource Locator">URL</acronym> (e.g. <a href="http://localhost:8080/uidl/carsales/carsales.uidl" class="urlextern" title="http://localhost:8080/uidl/carsales/carsales.uidl" rel="nofollow">http://localhost:8080/uidl/carsales/carsales.uidl</a>).
</p>

<p>
The CarSales examples allows of use of either Spring remoting or JSON-<acronym title="Remote Procedure Call">RPC</acronym> as a transport layer. The example also reveals how transparently the remoting implementation can be switched.
</p>

<p>
The UIDL source code for the application is located under ”<code>/webapp/carsales</code>”. The Java code for the server side is located under ”<code>/examples/net/uidl/carsales/</code>”.
</p>

<p>
<a href="http://www.uidl.net/dokuwiki/lib/exe/fetch.php?cache=cache&amp;media=http%3A%2F%2Fjava.uidl.net%2Fdoc%2Fimages%2FCarSales.GIF" class="media" title="http://java.uidl.net/doc/images/CarSales.GIF"><img src="index_files/fetch_003.gif" class="media" alt=""></a>
</p>

<p>
Basically, the CarSales application allows you to add as many makes as
you like (e.g. Alfa, Fiat, Ferrari). You can then add models to these
makes (MAKE_MODEL association) In a similar way, you can create
customers and associate make preferences with each customer. You can
also create options (heated seats, metallic paint, etc.) and associate
these with wither the make or the model. All data is persisted in real
time in the Derby embedded database on the server.
</p>

</div>

<h4><a name="uidl_security" id="uidl_security">UIDL Security</a></h4>
<div class="level4">

<p> Most enterprise class applications will require some form of
security, including the possibility to recognize and authenticate users
and assign appropriate roles. Rather than forcing application
developers to implement custom solutions to satisfy these requirements,
the UIDL environment aims to make it as easy as possible to implement
security in UIDL applications.
</p>

<p>
Given that the UIDL browser uses <acronym title="Hyper Text Transfer Protocol">HTTP</acronym> to transport UIDL scripts and <acronym title="Hyper Text Transfer Protocol">HTTP</acronym> for all remoting operations (unless a custom remote object mechanism is used), one can make use of existing <acronym title="Hyper Text Transfer Protocol">HTTP</acronym> security standards such as HTTPS and realm based authentication.
</p>

<p>
Specifically, the following code within the web descriptor (<code>web.xml</code>)
of the UIDL web application is sufficient to protect not only the
downloading of the UIDL scripts but also any method calls which might
be issued from a script. Finer grained security can obviously be
implemented if required.
</p>

<p>The UIDL browser (running in either applet or Java Web Start mode)
will use a dialog box to prompt the user for credentials the first time
he accesses a protected resource. Note that the realm will need to be
configured on the web server / web application server in order for this
type of security to function. Typically a realm is linked to an LDAP
directory containing user information.
</p>
<pre class="code xml">    <span class="sc3"><span class="re1">&lt;security-constraint<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;display-name<span class="re2">&gt;</span></span></span>Admin Security Constraint<span class="sc3"><span class="re1">&lt;/display-name<span class="re2">&gt;</span></span></span>
&nbsp;
       <span class="sc3"><span class="coMULTI">&lt;!-- protect Spring method calls --&gt;</span></span>
       <span class="sc3"><span class="re1">&lt;web-resource-collection<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;web-resource-name<span class="re2">&gt;</span></span></span>Spring Remoting<span class="sc3"><span class="re1">&lt;/web-resource-name<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;url-pattern<span class="re2">&gt;</span></span></span>/remote/*<span class="sc3"><span class="re1">&lt;/url-pattern<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;/web-resource-collection<span class="re2">&gt;</span></span></span>
&nbsp;
       <span class="sc3"><span class="coMULTI">&lt;!-- protect JSON-RPC method calls --&gt;</span></span>
       <span class="sc3"><span class="re1">&lt;web-resource-collection<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;web-resource-name<span class="re2">&gt;</span></span></span>Spring Remoting<span class="sc3"><span class="re1">&lt;/web-resource-name<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;url-pattern<span class="re2">&gt;</span></span></span>/JSON-RPC/*<span class="sc3"><span class="re1">&lt;/url-pattern<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;/web-resource-collection<span class="re2">&gt;</span></span></span>
&nbsp;
       <span class="sc3"><span class="coMULTI">&lt;!-- protect UIDL script download --&gt;</span></span>
       <span class="sc3"><span class="re1">&lt;web-resource-collection<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;web-resource-name<span class="re2">&gt;</span></span></span>UIDL Scripts<span class="sc3"><span class="re1">&lt;/web-resource-name<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;url-pattern<span class="re2">&gt;</span></span></span>/scripts/*.uidl<span class="sc3"><span class="re1">&lt;/url-pattern<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;/web-resource-collection<span class="re2">&gt;</span></span></span>
&nbsp;
       <span class="sc3"><span class="re1">&lt;auth-constraint<span class="re2">&gt;</span></span></span>
          <span class="sc3"><span class="re1">&lt;role-name<span class="re2">&gt;</span></span></span>Admin<span class="sc3"><span class="re1">&lt;/role-name<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;/auth-constraint<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;/security-constraint<span class="re2">&gt;</span></span></span>
&nbsp;
    <span class="sc3"><span class="coMULTI">&lt;!-- Define the Login Configuration for this Application --&gt;</span></span>
    <span class="sc3"><span class="re1">&lt;login-config<span class="re2">&gt;</span></span></span>
      <span class="sc3"><span class="re1">&lt;auth-method<span class="re2">&gt;</span></span></span>BASIC<span class="sc3"><span class="re1">&lt;/auth-method<span class="re2">&gt;</span></span></span>
      <span class="sc3"><span class="re1">&lt;realm-name<span class="re2">&gt;</span></span></span>Admin Security Constraint<span class="sc3"><span class="re1">&lt;/realm-name<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;/login-config<span class="re2">&gt;</span></span></span>
&nbsp;
    <span class="sc3"><span class="re1">&lt;security-role<span class="re2">&gt;</span></span></span>
       <span class="sc3"><span class="re1">&lt;role-name<span class="re2">&gt;</span></span></span>Admin<span class="sc3"><span class="re1">&lt;/role-name<span class="re2">&gt;</span></span></span>
    <span class="sc3"><span class="re1">&lt;/security-role<span class="re2">&gt;</span></span></span></pre>
</div>

    <!-- wikipage stop -->
  </div>

  <div class="clearer">&nbsp;</div>

  
  <div class="stylefoot">

    <div class="meta">
      <div class="user">
        Logged in as: Admin      </div>
      <div class="doc">
        uidldocumentation.txt · Last modified: 2008/01/12 14:37 by admin      </div>
    </div>

   
    <div class="bar" id="bar__bottom">
      <div class="bar-left" id="bar__bottomleft">
        <form class="button" method="post" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="edit" type="hidden"><input name="rev" value="" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Edit this page" class="button" accesskey="e" title="Edit this page [ALT+E]" type="submit"></div></form>        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="revisions" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Old revisions" class="button" accesskey="o" title="Old revisions [ALT+O]" type="submit"></div></form>      </div>
      <div class="bar-right" id="bar__bottomright">
                <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="admin" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Admin" class="button" title="Admin" type="submit"></div></form>        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="profile" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Update Profile" class="button" title="Update Profile" type="submit"></div></form>        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="logout" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Logout" class="button" title="Logout" type="submit"></div></form>        <form class="button" method="get" action="/dokuwiki/doku.php"><div class="no"><input name="do" value="index" type="hidden"><input name="id" value="uidldocumentation" type="hidden"><input value="Index" class="button" accesskey="x" title="Index [ALT+X]" type="submit"></div></form>        <a class="nolink" href="#dokuwiki__top"><input class="button" value="Back to top" onclick="window.scrollTo(0, 0)" title="Back to top" type="button"></a>&nbsp;
      </div>
      <div class="clearer"></div>
    </div>

  </div>

</div>

<div class="footerinc">
  <a href="http://www.uidl.net/dokuwiki/feed.php" title="Recent changes RSS feed"><img src="index_files/button-rss.png" alt="Recent changes RSS feed" height="15" width="80"></a>

  <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/" rel="license" title="Creative Commons License"><img src="index_files/button-cc.gif" alt="Creative Commons License" height="15" width="80"></a>

  <a href="https://www.paypal.com/xclick/business=andi%40splitbrain.org&amp;item_name=DokuWiki+Donation&amp;no_shipping=1&amp;no_note=1&amp;tax=0&amp;currency_code=EUR&amp;lc=US" title="Donate"><img src="index_files/button-donate.gif" alt="Donate" height="15" width="80"></a>

  <a href="http://www.php.net/" title="Powered by PHP"><img src="index_files/button-php.gif" alt="Powered by PHP" height="15" width="80"></a>

  <a href="http://validator.w3.org/check/referer" title="Valid XHTML 1.0"><img src="index_files/button-xhtml.png" alt="Valid XHTML 1.0" height="15" width="80"></a>

  <a href="http://jigsaw.w3.org/css-validator/check/referer?profile=css3" title="Valid CSS"><img src="index_files/button-css.png" alt="Valid CSS" height="15" width="80"></a>

  <a href="http://wiki.splitbrain.org/wiki:dokuwiki" title="Driven by DokuWiki"><img src="index_files/button-dw.png" alt="Driven by DokuWiki" height="15" width="80"></a>



<!--

<rdf:RDF xmlns="http://web.resource.org/cc/"
    xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<Work rdf:about="">
   <dc:type rdf:resource="http://purl.org/dc/dcmitype/Text" />
   <license rdf:resource="http://creativecommons.org/licenses/by-nc-sa/2.0/" />
</Work>

<License rdf:about="http://creativecommons.org/licenses/by-nc-sa/2.0/">
   <permits rdf:resource="http://web.resource.org/cc/Reproduction" />
   <permits rdf:resource="http://web.resource.org/cc/Distribution" />
   <requires rdf:resource="http://web.resource.org/cc/Notice" />
   <requires rdf:resource="http://web.resource.org/cc/Attribution" />
   <prohibits rdf:resource="http://web.resource.org/cc/CommercialUse" />
   <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks" />
   <requires rdf:resource="http://web.resource.org/cc/ShareAlike" />
</License>

</rdf:RDF>

-->


</div>

<div class="no"><img src="index_files/indexer.gif" alt="" height="1" width="1"></div>

</body></html>